# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
imports:
  pagination: ./utils/pagination.yml
  commons: ./commons.yml
service:
  auth: true
  base-path: /api/public
  endpoints:
    batch:
      docs: Batched ingestion for Langfuse Tracing
      method: POST
      path: /ingestion
      request:
        name: IngestionRequest
        body:
          properties:
            batch: list<IngestionEvent>
      response: IngestionResponse # will be reportet as 200 response, but endpoint returns 207

types:
  IngestionEvent:
    discriminant: "type"
    union:
      trace-create: TraceEvent
      score-create: ScoreEvent
      event-create: CreateEventEvent
      generation-create: CreateGenerationEvent
      generation-update: UpdateGenerationEvent
      span-create: CreateSpanEvent
      span-update: UpdateSpanEvent
      sdk-log: SDKLogEvent

      # both are legacy
      observation-create:
        type: CreateObservationEvent
        docs: Deprecated event type
      observation-update:
        type: UpdateObservationEvent
        docs: Deprecated event type

  ObservationType:
    enum:
      - SPAN
      - GENERATION
      - EVENT

  IngestionUsage:
    discriminated: false
    union:
      - commons.Usage
      - OpenAIUsage

  OpenAIUsage:
    docs: Usage interface of OpenAI for improved compatibility.
    properties:
      promptTokens: optional<integer>
      completionTokens: optional<integer>
      totalTokens: optional<integer>

  OptionalObservationBody:
    properties:
      traceId: optional<string>
      name: optional<string>
      startTime: optional<datetime>
      metadata: optional<unknown>
      input: optional<unknown>
      output: optional<unknown>
      level: optional<commons.ObservationLevel>
      statusMessage: optional<string>
      parentObservationId: optional<string>
      version: optional<string>

  CreateEventBody:
    extends: OptionalObservationBody
    properties:
      id: optional<string>

  UpdateEventBody:
    extends: OptionalObservationBody
    properties:
      id: string

  CreateSpanBody:
    extends: CreateEventBody
    properties:
      endTime: optional<datetime>

  UpdateSpanBody:
    extends: UpdateEventBody
    properties:
      endTime: optional<datetime>

  CreateGenerationBody:
    extends: CreateSpanBody
    properties:
      completionStartTime: optional<datetime>
      model: optional<string>
      modelParameters: optional<map<string, commons.MapValue>>
      usage: optional<IngestionUsage>
      promptName: optional<string>
      promptVersion: optional<integer>

  UpdateGenerationBody:
    extends: UpdateSpanBody
    properties:
      completionStartTime: optional<datetime>
      model: optional<string>
      modelParameters: optional<map<string, commons.MapValue>>
      usage: optional<IngestionUsage>
      promptName: optional<string>
      promptVersion: optional<integer>

  ObservationBody:
    properties:
      id: optional<string>
      traceId: optional<string>
      type: ObservationType
      name: optional<string>
      startTime: optional<datetime>
      endTime: optional<datetime>
      completionStartTime: optional<datetime>
      model: optional<string>
      modelParameters: optional<map<string, commons.MapValue>>
      input: optional<unknown>
      version: optional<string>
      metadata: optional<unknown>
      output: optional<unknown>
      usage: optional<commons.Usage>
      level: optional<commons.ObservationLevel>
      statusMessage: optional<string>
      parentObservationId: optional<string>

  TraceBody:
    properties:
      id: optional<string>
      timestamp: optional<datetime>
      name: optional<string>
      userId: optional<string>
      input: optional<unknown>
      output: optional<unknown>
      sessionId: optional<string>
      release: optional<string>
      version: optional<string>
      metadata: optional<unknown>
      tags: optional<list<string>>
      public:
        type: optional<boolean>
        docs: Make trace publicly accessible via url

  SDKLogBody:
    properties:
      log: unknown

  ScoreBody:
    properties:
      id: optional<string>
      traceId: string
      name: string
      value: double
      observationId: optional<string>
      comment: optional<string>

  BaseEvent:
    properties:
      id: string
      timestamp: string
      metadata: unknown

  TraceEvent:
    extends: BaseEvent
    properties:
      body: TraceBody

  CreateObservationEvent:
    extends: BaseEvent
    properties:
      body: ObservationBody

  UpdateObservationEvent:
    extends: BaseEvent
    properties:
      body: ObservationBody

  ScoreEvent:
    extends: BaseEvent
    properties:
      body: ScoreBody

  SDKLogEvent:
    extends: BaseEvent
    properties:
      body: SDKLogBody

  CreateGenerationEvent:
    extends: BaseEvent
    properties:
      body: CreateGenerationBody

  UpdateGenerationEvent:
    extends: BaseEvent
    properties:
      body: UpdateGenerationBody

  CreateSpanEvent:
    extends: BaseEvent
    properties:
      body: CreateSpanBody

  UpdateSpanEvent:
    extends: BaseEvent
    properties:
      body: UpdateSpanBody

  CreateEventEvent:
    extends: BaseEvent
    properties:
      body: CreateEventBody

  IngestionSuccess:
    properties:
      id: string
      status: integer

  IngestionError:
    properties:
      id: string
      status: integer
      message: optional<string>
      error: optional<unknown>

  IngestionResponse:
    properties:
      successes: list<IngestionSuccess>
      errors: list<IngestionError>
